package net.xdclass.component;

import com.amazonaws.services.s3.model.Bucket;
import com.amazonaws.services.s3.model.S3ObjectSummary;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.web.multipart.MultipartFile;
import java.util.List;

/**
 * 存储引擎接口，用于定义对象存储服务的基本操作
 */
public interface StoreEngine {

    /*============================Bucket相关=========================*/

    /**
     * 判断指定名称的Bucket是否存在
     *
     * @param bucketName Bucket名称
     * @return 是否存在
     */
    boolean bucketExists(String bucketName);

    /**
     * 删除指定名称的Bucket
     *
     * @param bucketName Bucket名称
     * @return 删除是否成功
     */
    boolean removeBucket(String bucketName);

    /**
     * 创建一个新的Bucket
     *
     * @param bucketName Bucket名称
     */
    void createBucket(String bucketName);

    /**
     * 获取所有Bucket列表（可带过滤条件）
     *
     * @param bucketName 过滤条件（可选）
     * @return Bucket列表
     */
    List<Bucket> getAllBucket(String bucketName);



    /*============================文件相关=========================*/

    /**
     * 列出指定Bucket中的所有对象
     *
     * @param bucketName Bucket名称
     * @return 对象摘要列表
     */
    List<S3ObjectSummary> listObjects(String bucketName);

    /**
     * 判断指定对象是否存在于Bucket中
     *
     * @param bucketName Bucket名称
     * @param objectKey  对象键名
     * @return 是否存在
     */
    boolean doesObjectExist(String bucketName, String objectKey);

    /**
     * 从本地文件上传到指定Bucket
     *
     * @param bucketName     Bucket名称
     * @param objectKey      目标对象键名
     * @param localFileName  本地文件路径
     * @return 上传是否成功
     */
    boolean upload(String bucketName, String objectKey, String localFileName);

    /**
     * 从MultipartFile上传到指定Bucket
     *
     * @param bucketName Bucket名称
     * @param objectKey  目标对象键名
     * @param file       上传的文件
     * @return 上传是否成功
     */
    boolean upload(String bucketName, String objectKey, MultipartFile file);

    /**
     * 删除指定Bucket中的对象
     *
     * @param bucketName Bucket名称
     * @param objectKey  对象键名
     * @return 删除是否成功
     */
    boolean delete(String bucketName, String objectKey);



    /*============================下载相关=========================*/

    /**
     * 将指定对象内容写入HTTP响应流进行下载
     *
     * @param bucketName Bucket名称
     * @param objectKey  对象键名
     * @param response   HTTP响应对象
     */
    void download2Response(String bucketName, String objectKey, HttpServletResponse response);

}
